Configuration Portability

Organizations often set up test systems when they implement major changes to an existing production system. The test system is analyzed to ensure that all changes have been applied correctly before updating the production environment. It is imperative for organizations to follow this procedure in order to reduce the likelihood of errors or failures when these changes are implemented on the production system.

vFire Core systems are business-critical and require complex configuration and setup by administrators. As a result, it is typical to set up a test system for vFire Core, ensure the setup reflects the organization’s requirements, make changes if required, and then recreate the settings and data from the test system into the production system. Depending on the scale of an organization’s operations, this task can be time-consuming.

Configuration Portability enables you to copy selected configuration settings from one system to another system using a simple export and import mechanism. All this can be performed directly from the client application, which means that you do not need to have access to the vFire Core server to import and export configuration settings. This saves time and minimizes human error by avoiding the need to manually configure two identical systems if moving from a test environment to a live environment. 

Once an organization has developed screens and configured settings on a development system (referred to as the source), the changes are imported and validated in the test system (referred to as the target ), and then imported into the production system (referred to as the master target ). Configuration Portability enables you to select the configuration settings you want to copy, export the settings from the source system, and then import them into the master target system.

You can transfer administration settings pertaining to functional areas such as Service Desk, Workflow Management, Configuration Management and Service Level Management. The following data can be ported:

  • System Administration settings
  • Screens, forms, and message templates configured in the Designer

The following cannot be ported:

  • System default values (such as the default System Title defined in System Administration)
  • Templates (such as Workflow Templates and Call Templates)
  • IPK Workflow Rules
  • Forum Management Rules
  • Reports
  • Activity Logs
  • Person records
  • Passwords and Email settings
  • System customizations, stored procedures, and integration settings. (These settings involve files which are not located within the database, such as SQL files, or HTML files.) They must be transferred manually between the source and the target systems.
  • Integration Platform settings

Workflow templates can be ported through the Server Console.

Prerequisites and Considerations

Please note the following requirements and recommendations.

  • You must only port from a single source system, that is, you cannot port from multiple systems into one target system. This means that you must use configuration portability in a serialized release environment. Refer to the Config Port Overview & Best Practices topic for more information.
  • Ensure the same version of the software is installed on both the source and target systems.
  • Back up your target system before porting data.
  • If your system has been customized, it is recommended Alemba Professional Services assists you in porting data between systems.
  • Note the specific instructions for Config Portability with CSV Connectors (Upload option) below.
  • When Configuration Portability is used to make changes to a production environment, the production settings should not be changed manually. This is to prevent data mismatches and the potential for unexpected behavior.
  • Partition settings play a major role in determining how your vFire Core system functions. Importing to or exporting from a system that has partitioning enabled and subsequently disabled may result in random errors in the export and import process. In addition, partition names must be unique for the process to be successful.

Rules for Supported Options

Certain settings have specific rules applied to them when they are imported into the target system. The table below lists the rules for such options.

Option or Setting to be Imported Import Condition / Rule
IPK and Workflow Management Groups The recipient analyst and partition settings must match in the source and target systems.
Stored Procedures Only the settings for stored procedures are imported, not the stored procedures themselves.
IPK Management Security Role The Screen Sets tab is displayed on the IPK Management Security Role window when IPK statuses and streams are not enabled. If a call screen set does not exist on the target system, the corresponding role is created but will not have the screens linked to it. This action will be recorded in the import log.
Call, Customer Survey, Request and Task Screen Sets To export and import screens and data schema, the appropriate screen sets must be selected under the Screens, Forms and/or Message Templates tabs. This will process all screens for that screen set. Alternatively you may select individual screens from Screens – Individual. Selecting the screen sets in the IPK Management or Workflow Management tabs will only import the screen set names.
Knowledge screens When knowledge screens are copied, Knowledge Entry Types and Knowledge Base types are also copied because they are dependent settings.

How Configuration Portability Works

The data transfer between two systems is a two-step process. The data must first be exported from the source system (for example, the development environment), and then imported into the target system (for example, the test or pre-production environment) or the master target system (for example, the production environment).

To copy data between two systems, a common mechanism for matching the source and target data is used. vFire Core applies a Global Unique Identifier (GUID) as the matching key to each database entry across database instances. This allows renamed text fields, for example, to be recognized during the import process. Two items with different GUIDs are identified as different items.

Before exporting the production database to the development system, it is recommended that you first run the Config Portability GUID Assignment.scp via the server console to allocate unique identifiers (GUIDs) to any fields missing a GUID so the system properties remain synchronized when using Configuration Portability.

Custom schema files go in the Config directory and allow you to add additional elements. Schema files are version specific and this option should only be used by an experienced developer.

The following reconciliation rules are applied when configuration data is imported to a system with existing data:

    In the explanations below, "target" refers to both a target system and a master target system.

  • Items in the source and target systems are identified as being the same if the target item does not have a GUID, but has the same entity and partition as the item in the source system. The target item is then filled with the GUID from the source.
  • If a value is active in the source system and no matching value is found in the target system, a new value (same as that in the source) is created in the target system. If the partition is not relevant, it is not considered as a reconciliation criterion.

    • If the Finance workflow group (present in the source system) does not exist in the target system, it is added in the target system.

    Insertion of items with the same names as existing items in the target system is allowed.

  • If a value exists in the target system but not in the source system, the value in the target system is kept (it is not deleted).
  • If a value has been deleted in the source system, it is imported into the target system as a deleted value.
  • If a value in the target system matches one in the source system but it is a deleted value, the value is marked as active if it is active in the source system.
  • If matching deleted values are found on the source and target systems, no change is made to the target system.
  • After an import, the names and statuses (active/passive) of the items imported in the target system are kept the same as the names and statuses of their matching source items.

    • If the name or status of the matching source item is different, the name or status of the target item is changed to that of the source item (whether the latest change to the target item was manual or automatic).

    Name case is not taken into consideration for name matching. In addition, if the GUID is not present in the target item (that is, porting has not occurred), the whitespace character (represented below with “_” character) in the name of the target item is affected as follows -

    “Significant_” is replaced with “Significant”
    “_Significant” is not replaced. Instead, a new “Significant” is added to the target

  • After an import, the relative order hierarchy of the items imported in the target system is the same as the relative order hierarchy of their matching source items. This means that:
    • When inserting a new item in the target system, the item is ordered below another item that has the same order hierarchy.
    • When reordering a new item in the target system, the item is ordered below the item that has the same order hierarchy.
    • The relative order hierarchy of target items with no matching source items is kept as is.

    • For example, if the source system has Low > Medium > High and the target system has High > Mediocre > Low > Insignificant, the resulting order in the target system will be: Low > Mediocre > Medium > High > Insignificant

    Items that can be ordered hierarchically include administrative values where users specify ordering by using the pair of up and down arrows in the toolbar (for example, the Call Priority options).

  • All dependent settings are automatically imported (for example, call screen set names are imported when call screen sets are imported). If the dependency is not imported for any particular reason (for example, the person does not exist in the target system), a log is written.

Config Portability with CSV Connectors (Upload option)

If you are using the CSV connector, you should note that from 9.8 onwards, you are porting the settings, but not the CSV file itself. Therefore, when porting the settings for a CSV connector, take the following steps:

  1. Export the CSV Connector Settings from the source system.
  2. Import the CSV Connector Settings into the target system.
  3. Open the CSV Connector Source in the target system.
  4. Upload the CSV File.
  5. Click to confirm that the target connector source system is working as expected.
  6. Configure/review the Integration Resource, etc. as usual.

Working with Individual Screens, Forms and Message Templates

You can export individual Screens, Forms and Message Templates.

Only designable screens will be available for export. Non designer screens will have to be copied manually. The scope of the data is limited to the selected screen and directly related items.

The imported/exported information for these items is only displayed on the By Selection tab. These items are only a subset of the screen designer options, so are not relevant By Section.

Parent screen sets which are not found in the target systems will have some values set to defaults. These items include IMAGE_REF and REPORT_REF. To keep this information consistent, it is recommended to select the CMDB Item Types option as well.

Additional Data Exported

  • Screen Set including parents
  • Security Profiles
  • Security Profile Access
  • Partitions
  • Extension Fields

Screens containing references to extension fields on other screens

If needing to port a screen which contains references to extension fields on another screen (such as in filters or rules, or linked fields) both screens need to be included in the Config Port, and the import needs to be run twice on the target system(s) using the same config file.

If this is not done, the rules in the target system will appear correct but will not work.

Example scenario: Screen A contains a rule that references a field on screen B
1. Export both screens from the source system
2. Import the config file into the target system (this creates the field)
3. Import the same config file into the target system a second time (this links the field to the rule)

For systems on a version lower than vFire Core 9.5, the second import (step 3) will not link the fields. In this situation ignore step 3 and manually recreate the rules or filters, or re-add the linked field as needed.

Exceptions

Case Description
Selecting an entire screen set and individual options If a user selects a screen set under the Screens, Forms, and/or Message Templates tab, any individual Screens, Forms, and/or Message Templates selected for that screen set will be ignored. This is because the screen set and its associated types are already marked for export.
Linked Fields on Individual Screens If there are fields linked to a screen set from another screen set, these fields will be imported and linked to the screen. They will not be linked to the original screen, even if it exists.
Linked Extension Field of another Extension field These fields will be ignored and the field definition will be left untouched in the source html
Importing Individual Screens Screens will only be available for import if they were exported as individual screens. You cannot export Screens -> Call and then import only selected screen sets.